docs: split user and maintainer docs, fix 100+ stale claims by t3dotgg · Pull Request #4807 · pingdotgg/t3code

t3dotgg · 2026-07-29T01:14:12Z

Our docs had drifted badly: the "Getting started" links sent end users into stale build-from-source content (`bun run` commands we don't use), the index linked a docs/mobile/ section that no longer exists, and an evidence-based audit of all 31 docs found 109 stale, wrong, or broken claims — including a release runbook step labeled "dry-run" that actually publishes to npm `latest` and aliases app.t3.codes.

This PR restructures docs by audience and fixes every confirmed finding.

Structure (all moves via `git mv`):

`docs/user/` — everything an end user reads. Gains a new `install.md`, the provider guides, source control, `permission-modes.md` (was `architecture/runtime-modes.md`), and `updating.md` (renamed from `server-updates.md` to end the name collision).
`docs/internals/` — replaces `architecture/` + `reference/` + `cloud/` + `operations/ci.md`. `encyclopedia.md` is now `glossary.md`.
`docs/operations/` — real runbooks only.
Deleted: `quick-start.md`, `codex-prerequisites.md`, `effect-fn-checklist.md` (22 broken links, obsolete), `project/todo.md` (every item shipped).

Content highlights:

release.md no longer claims a dry-run tag path exists; pushing any non-nightly tag is documented as a real stable release.
Fixed instructions that silently failed: Claude multi-account login (`CLAUDE_CONFIG_DIR`, not `HOME`), keybindings config path (`~/.t3/userdata/`), the false "GUIs can't add remote projects" limitation, version-skew update commands, Cursor's `agent login`.
`internals/overview.md` and `providers.md` rewritten around the actual Effect RPC boundary and five-provider driver registry (they described a retired transport and claimed Codex was the only provider).
README and `docs/README.md` rewritten: user links only up top, one clearly-labeled door to contributor docs.
Conventions: maintainer blockquote on internals/operations docs, no source paths in user docs, no `#L` line anchors, link-don't-copy for enums/tables.
Follow-up commit removes the Connect waitlist flow docs (waitlist was removed on main in Remove Connect waitlist and add GA announcement tooling #4691).

Every fix was verified against source before writing. All relative links across the tree resolve.

Changes by Claude Fable 5 via Claude Code (multi-agent workflow: gpt-5.6-sol fact-checkers, Opus 5 + Fable 5 writers).

🤖 Generated with Claude Code

Note

Low Risk
Documentation-only changes with no runtime or API impact; risk is limited to broken links or misleading instructions if any fix was wrong.

Overview
This PR restructures the docs tree by audience and corrects widespread stale or misleading content that had drifted from the product and codebase.

Structure: End-user material lives under docs/user/ (new install.md, permission-modes.md, renamed updating.md, provider and source-control guides). Maintainer content moves to docs/internals/ (architecture, glossary, connection runtime, providers, remote, scripts, CI). docs/operations/ keeps runbooks only. Obsolete pages (quick-start, codex-prerequisites, effect-fn-checklist, project/todo) are removed; encyclopedia becomes internals/glossary.md.

Content fixes: Release docs no longer describe a “dry-run” tag that still publishes to npm latest and aliases app.t3.codes. User docs fix Claude multi-account (CLAUDE_CONFIG_DIR not HOME), keybindings path (~/.t3/userdata/), Cursor login (agent login), remote project addition and Tailscale HTTPS toggles, Bitbucket T3CODE_BITBUCKET_ACCESS_TOKEN, and version-skew service update commands. Internals rewrites overview and providers around Effect RPC and five built-in drivers (replacing retired transport/Codex-only descriptions). AGENTS.md, root README, and infra/relay/README point at the new paths; maintainer docs use a standard “for maintainers” blockquote and user docs avoid repo tooling paths.

^{Reviewed by Cursor Bugbot for commit b65c6a4. Bugbot is set up for automated code reviews on this repo. Configure here.}

Note

Split user and maintainer docs and fix stale claims across 100+ documentation files

Reorganizes docs into three audience-based directories: docs/user/ for end-user guides, docs/internals/ for maintainer/architecture references, and docs/operations/ for runbooks; updates docs/README.md index accordingly.
Adds new maintainer docs covering workspace layout, build scripts, CI gates, connection runtime, provider architecture, and remote/environment architecture.
Fixes stale content across existing docs: corrects token TTLs, permission mode names, keybinding config paths, update commands, provider config env vars (CLAUDE_CONFIG_DIR), and Bitbucket auth precedence.
Renames and moves ~15 files (e.g. docs/cloud/ → docs/internals/, docs/integrations/ → docs/user/) and updates all cross-references in AGENTS.md, README.md, and infra/relay/README.md.

^{Macroscope summarized b65c6a4.}

coderabbitai · 2026-07-29T01:14:20Z

Important

Review skipped

Auto reviews are disabled on this repository. Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Repository UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 67bbfb98-30d1-4513-8b4a-13c27afa1c5e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

🔍 Trigger review

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

macroscopeapp · 2026-07-29T01:29:15Z

Approvability

Verdict: Approved b65c6a4

Documentation-only changes: reorganizes docs by audience (user vs maintainer), fixes stale claims, and updates cross-references. No runtime code or configuration is affected.

^{You can customize Macroscope's approvability policy. Learn more.}

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Dismissing prior approval to re-evaluate 0b88f45

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Dismissing prior approval to re-evaluate b65c6a4

The example path in the self-reference rule still named `docs/providers/claude.md`, which upstream pingdotgg#4807 renamed. Same rule, live path. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>

27 commits from main, including the ⌘P file picker / ⇧⌘F content search (#4855), thread content search (#4959), sidebar title regeneration (#4810), image-paste compression (#4967), and the docs restructure (#4807). Notable resolutions beyond keep-both: - Thread content search is ported to the v2 surface: searchThreads joins ORCHESTRATION_V2_WS_METHODS/rpc/auth scopes, and the SQL now UNIONs orchestration_v2_projection_messages so current threads are searchable, not just legacy-projected ones. - Title regeneration's server half lived in the v1 ProviderCommandReactor this branch deletes, so the capability is deliberately not advertised: clients hide the action, the contract/UI code stays intact, and the input field is accepted as a documented no-op. TODO(orchestration-v2): port regeneration to the v2 runtime. - Main's 035_ProjectionThreadTitleRegeneration migration collided with this branch's 035-043 range; renumbered to 044. - Mobile activity grouping keeps this branch's runId/prominence semantics while adopting main's O(1) trailing-group optimization (prominence tracked in a flag instead of a per-append scan). - v1-only startup tests from main (heartbeat/auto-bootstrap against the deleted reactor-era services) are dropped; their v2 equivalents already cover the ordered startup phases. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

@t3dotgg

## What's Changed * docs: split user and maintainer docs, fix 100+ stale claims by @t3dotgg in pingdotgg/t3code#4807 * fix(web): server updates no longer look like warnings by @t3dotgg in pingdotgg/t3code#4992 * fix(connect): reboots no longer strand the relay link, 403s now say why by @t3dotgg in pingdotgg/t3code#4988 * Add project file picker (⌘P) and project content search (⇧⌘F) by @jakeleventhal in pingdotgg/t3code#4855 * Check for mobile app updates on launch by @juliusmarminge in pingdotgg/t3code#4958 **Full Changelog**: pingdotgg/t3code@v0.0.32-nightly.20260730.956...v0.0.32-nightly.20260730.957 Upstream release: https://github.com/pingdotgg/t3code/releases/tag/v0.0.32-nightly.20260730.957

github-actions Bot added vouch:trusted PR author is trusted by repo permissions or the VOUCHED list. size:XXL 1,000+ changed lines (additions + deletions). labels Jul 29, 2026

macroscopeapp Bot reviewed Jul 29, 2026

View reviewed changes

Comment thread docs/user/permission-modes.md Outdated

Comment thread docs/internals/scripts.md Outdated

Comment thread docs/operations/observability.md Outdated

Comment thread docs/internals/remote.md Outdated

macroscopeapp Bot reviewed Jul 29, 2026

View reviewed changes

Comment thread docs/internals/remote.md Outdated

macroscopeapp Bot previously approved these changes Jul 29, 2026

View reviewed changes

t3dotgg and others added 6 commits July 30, 2026 05:40

docs: split user and maintainer docs, fix 100+ stale claims

9e7d0f5

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: drop removed Connect waitlist flow from t3-connect docs

fefaf98

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: address macroscope review findings

93edfe5

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: clarify relay tunnel vs worker hot path in remote.md

718c6c3

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: fix markdown table formatting

3576e00

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

docs: fold post-split main changes into the new tree

0b88f45

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

t3dotgg force-pushed the t3code/review-docs-split branch from 5293e89 to 0b88f45 Compare July 30, 2026 12:43

macroscopeapp Bot reviewed Jul 30, 2026

View reviewed changes

Comment thread docs/internals/environment-auth.md

Comment thread docs/user/permission-modes.md Outdated

Comment thread docs/internals/overview.md Outdated

macroscopeapp Bot previously approved these changes Jul 30, 2026

View reviewed changes

docs: address second-round macroscope findings

b65c6a4

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

macroscopeapp Bot approved these changes Jul 30, 2026

View reviewed changes

t3dotgg merged commit 9dd425b into main Jul 30, 2026
16 checks passed

t3dotgg deleted the t3code/review-docs-split branch July 30, 2026 13:10

t3code-tarik02 Bot mentioned this pull request Jul 30, 2026

prepare stable release 2026.7.3000 tarik02-org/t3code#95

Open

NoahHendrickson mentioned this pull request Jul 30, 2026

sync: absorb upstream v0.0.31 (34 commits) NoahHendrickson/t3code#38

Merged

aaditagrawal mentioned this pull request Jul 31, 2026

sync: port upstream resource diagnostics, thread search, file picker, docs split (#2679–#4992) aaditagrawal/t3code#195

Open

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs: split user and maintainer docs, fix 100+ stale claims - #4807

docs: split user and maintainer docs, fix 100+ stale claims#4807
t3dotgg merged 7 commits into
mainfrom
t3code/review-docs-split

t3dotgg commented Jul 29, 2026 •

edited by macroscopeapp Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 29, 2026 •

edited

Loading

Review skipped

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

macroscopeapp Bot commented Jul 29, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

t3dotgg commented Jul 29, 2026 • edited by macroscopeapp Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Split user and maintainer docs and fix stale claims across 100+ documentation files

Uh oh!

coderabbitai Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review skipped

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

macroscopeapp Bot commented Jul 29, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Approvability

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

t3dotgg commented Jul 29, 2026 •

edited by macroscopeapp Bot

Loading

coderabbitai Bot commented Jul 29, 2026 •

edited

Loading

macroscopeapp Bot commented Jul 29, 2026 •

edited

Loading